<chapter xml:id="to_text.h">
<title><tt>__vic/to_text.h</tt></title>

<p>Generic converters to some text representation.</p>


<chapter xml:id="to_text_append">
<title><tt>to_text_append()</tt></title>

<code-block lang="C++"><![CDATA[
void to_text_append(long long n, std::string &str);
void to_text_append(long n, std::string &str);
void to_text_append(int n, std::string &str);
void to_text_append(short n, std::string &str);
void to_text_append(signed char n, std::string &str);

void to_text_append(unsigned long long n, std::string &str);
void to_text_append(unsigned long n, std::string &str);
void to_text_append(unsigned n, std::string &str);
void to_text_append(unsigned short n, std::string &str);
void to_text_append(unsigned char n, std::string &str);

void to_text_append(long double n, std::string &str);
void to_text_append(double n, std::string &str);
void to_text_append(float n, std::string &str);

void to_text_append(bool f, std::string &str);

void to_text_append(const void *p, std::string &str);

void to_text_append(const std::string &st, std::string &s);
void to_text_append(const char *st, std::string &s);
void to_text_append(char ch, std::string &s);

#if __cpp_lib_string_view // C++17
void to_text_append(std::string_view sv, std::string &s);
#endif
]]></code-block>

<p>Converts the specified first argument to some text representation and
appends it to the second argument.</p>

<p>This function is a customization point (like <tt>std::swap</tt>) for the
library. Users can define additional overloads for own types (in the same
namespace where the type is defined) in order to "teach" the library how to
create a text from the value of the specified type.</p>

<note>This is not a replacement for such feature-rich formatting facilities
as <tt>std::format</tt> or <tt>std::sprintf</tt>. For example, there is no
way to represent an integer value in HEX or right-align it to the specified
width. The main purpose is the ability to represent the value in debug/log/error
messages in some human-readable form.</note>

<note><tt>signed char</tt> and <tt>unsigned char</tt> types are treated as
integers not characters!</note>

<synopsis>
<prototype>void to_text_append(long long n, std::string &amp;str)</prototype>
<prototype>void to_text_append(long n, std::string &amp;str)</prototype>
<prototype>void to_text_append(int n, std::string &amp;str)</prototype>
<prototype>void to_text_append(short n, std::string &amp;str)</prototype>
<prototype>void to_text_append(signed char n, std::string &amp;str)</prototype>
<prototype>void to_text_append(unsigned long long n, std::string &amp;str)</prototype>
<prototype>void to_text_append(unsigned long n, std::string &amp;str)</prototype>
<prototype>void to_text_append(unsigned n, std::string &amp;str)</prototype>
<prototype>void to_text_append(unsigned short n, std::string &amp;str)</prototype>
<prototype>void to_text_append(unsigned  char n, std::string &amp;str)</prototype>
<prototype>void to_text_append(long double n, std::string &amp;str)</prototype>
<prototype>void to_text_append(double n, std::string &amp;str)</prototype>
<prototype>void to_text_append(float n, std::string &amp;str)</prototype>
<p>Converts a number to decimal representation.</p>
</synopsis>

<synopsis>
<prototype>void to_text_append(bool f, std::string &amp;str)</prototype>
<p>Converts a boolean value to <tt>0</tt> or <tt>1</tt>.</p>
</synopsis>

<synopsis>
<prototype>void to_text_append(const void *p, std::string &amp;str)</prototype>
<p>Converts a pointer to some platform-specific representation.</p>
</synopsis>

<synopsis>
<prototype>void to_text_append(const std::string &amp;st, std::string &amp;s)</prototype>
<prototype>void to_text_append(const char *st, std::string &amp;s)</prototype>
<prototype>void to_text_append(char ch, std::string &amp;s)</prototype>
<prototype>void to_text_append(std::string_view sv, std::string &amp;s) <badge>C++17</badge></prototype>
<p>Appends the specified string or character to the output string.</p>
<note><tt>nullptr</tt> value in the <tt>const char *</tt> overload is threated
as an empty string.</note>
</synopsis>

<section><title>Example</title>
<code-block lang="C++">
int n = 5;
std::string st = "n = ";
__vic::to_text_append(n, st);
assert(st == "n = 5");
</code-block>
</section>

</chapter>

</chapter>
